io.Connect Desktop

6.19.0

io.Connect Desktop is a desktop integration platform that enables functional and visual integration of web, native and legacy apps.

The io.Connect JavaScript library enables web apps to participate in io.Connect Desktop and use io.Connect functionalities via a set of APIs.

Referencing

From a JavaScript File

io.Connect JavaScript is a library available as a single JavaScript file, which you can include in your web apps using a <script> tag:

<script type="text/javascript" src="desktop.umd.js"></script>

When deploying your app in production, it's recommended to always reference a specific minified version:

<script type="text/javascript" src="desktop.umd.min.js"></script>

From an NPM Module

The io.Connect JavaScript library is also available as an npm package, which you can include as a dependency in your project and import in your code. The currently available packages are @interopio/core and @interopio/desktop. The Core package is a subset of the Desktop package and offers basic functionalities for sharing data between apps (Interop, Shared Contexts, Pub/Sub, Metrics), while the Desktop package offers additional options for sharing data between apps (Channels), as well as advanced window management functionalities (App Management, Layouts, Window Management).

To install the io.Connect library in your project, execute the following command:

npm install @interopio/desktop

Initialization

The io.Connect Desktop library registers a global factory function called IODesktop() that will resolve with the initialized API object when invoked:

import IODesktop from "@interopio/desktop";

const io = await IODesktop();

Optionally, you can provide configuration for the library:

import IODesktop from "@interopio/desktop";

// Enabling the Channels API.
const config = { channels: true };

const io = await IODesktop(config);

Description

Instance of the initialized io.Connect library.

Properties

Property	Type	Description
appManager	API	App Management API.
apps	API	Apps API.
bus	API	Pub/Sub library.
channels	API	Channels API.
contexts	API	Contexts library.
cookies	API	Cookies API.
displays	API	Displays API.
hotkeys	API	Hotkeys API.
info	object	Info object containing versions of all included libraries and io.Connect itself.
insights	API	io.Insights library
intents	API	Intents API.
interception	API	Interception API. Available since io.Connect Desktop 9.6
interop	API	Interop library.
layouts	API	Layouts API.
logger	API
metrics	API	Metrics library.
notifications	API	Notifications API.
platform	API	Platform API.
prefs	API	App Preferences API.
themes	API	Themes API.
version	string	io.Connect version.
windows	API	Window Management API.
workspaces	API	Workspaces API.

Methods

done

feedback

donemethod

Signature

() => Promise<void>

Description

Disposes the io.Connect API. This will remove all Interop methods and streams registered by the application.

feedbackmethod

Signature

(info?: FeedbackInfo) => void

Description

Brings up the IOConnect Desktop feedback dialog.

Parameters

Name	Type	Required	Description
info	FeedbackInfo

Description

Authentication can use one of the following flows:

username/password;
token - access tokens can be generated after successful login from the Auth Provider (e.g., Auth0);
gatewayToken - Gateway tokens are time limited tokens generated by the Gateway after an explicit request. To generate one, use the io.connection.authToken() method;
sspi - using sessionId and authentication challenge callback;

Properties

Property	Type	Description
flowCallback	(sessionId: string, token: any) => Promise<{ data: any; }>
flowName	"sspi"
gatewayToken	string	Authenticate using gatewayToken
password	string	Password to be used
provider	string	GW auth provider to be used
providerContext	any	A context object, which will be passed along to the GW auth provider to be used to request verification
sessionId	string
token	string	Authenticate using token generated from the auth provider.
username	string	Username to be used

Description

Optional configuration object for initializing the io.Connect library.

Properties

Property	Type	Default	Description
application	string		Application name. If not specified, the value depends on the hosting environment. For the browser - `document.title + random number` (e.g., ClientList321333). In desktop - `containerName + browserWindowName` (e.g., Internal.ClientList).
appManager	boolean \| "startOnly" \| "skipIcons" \| "full"	"startOnly"	Initializes or disables the App Management API. You can also specify mode in which that App Management API will be initialized.
apps	boolean	false	Initializes or disables the Apps API.
auth	string \| Auth		Authentication can use one of the following flows: username/password; `token` - access tokens can be generated after successful login from the Auth Provider (e.g., Auth0); `gatewayToken` - Gateway tokens are time limited tokens generated by the Gateway after an explicit request. To generate one, use the `io.connection.authToken()` method; `sspi` - using `sessionId` and authentication challenge callback;
bus	boolean		Enable or disable the Pub/Sub API.
channels	boolean \| Configuration	false	Initializes or disables the Channels API.
contexts	boolean \| ContextsConfig		Enable, disable and configure the Contexts API.
customLogger	CustomLogger		Pass this to override the build-in logger and handle logging on your own
displays	boolean	true	Initializes or disables the Displays API.
exposeAPI	boolean	true	Determines whether io.Connect will share the initialized API object upon request via a custom web event.
gateway	GatewayConfig		Configurations for the io.Connect Gateway connection.
identity	{ [key: string]: string \| number \| boolean; }		Specify custom identity fields. Those can also override some of the system fields assigned
insights	boolean \| Settings		io.Insights settings for metrics, tracing and logging.
intents	Config		Configuration for the Intents Resolver UI.
layouts	boolean \| "full" \| "fullWaitSnapshot" \| "slim" \| Configuration	"slim"	Initializes or disables the Layouts API. You can also specify mode and configuration with which that Layouts API will be initialized.
libraries	((io: API, config?: Config) => Promise<void>)[]		A list of io.Connect factory functions that will be initialized internally to provide access to specific functionalities.
logger	"error" \| "info" \| "off" \| "trace" \| "debug" \| "warn" \| LoggerConfig		Defines logging levels per output target.
metrics	boolean \| MetricsConfig		Metrics configurations.
windows	boolean	true	Initializes or disables the Window Management API.

Description

Allows customizing the feedback form

Properties

Property	Type	Default	Required	Description
message	string			Will be added to the description field in the feedback form

Description

Configurations for the io.Connect Gateway connection.

Properties

Property	Type	Default	Description
gwTokenProvider	GwTokenProvider		A way to pass custom token provider for Gateway v.3 tokens.
inproc	InprocGWSettings		Connect with GW in memory
protocolVersion	number		Legacy (Version of the Gateway that you are connected to)
reconnectAttempts	number	10	Number of reconnect attempts.
reconnectInterval	number	500	Reconnect interval in milliseconds.
sharedWorker	string
webPlatform	WebPlatformConnection		An object containing the configuration settings when core is operating in a web platform environment
ws	string		URL for the WebSocket connections to the Gateway.

Properties

Property	Type	Default	Required	Description
facade	IOConnectCore

Properties

Property	Type	Default	Required	Description
console	LogLevel			Console logging level.
publish	LogLevel			File logging level. To allow logging to files in your apps, you must set the `"allowLogging"` top-level property to `true` in the app definition.

Description

Metrics configurations.

Properties

Property	Type	Default	Required	Description
disableAutoAppSystem	boolean			If `false` (default), an App system will be created on top level, and all other metrics will live in it. If `true`, an App system will be created, and all metrics will live on top level.
pagePerformanceMetrics	PagePerformanceMetricsConfig

Properties

Property	Type	Default	Required	Description
enabled	boolean
initialPublishTimeout	number
publishInterval	number

Properties

Property	Type	Default	Required	Description
forceTracing	boolean
traceparent	string
tracestate	string

Properties

Property	Type	Default	Description
additionalAttributes	{ [x: string]: unknown; } \| (() => { [x: string]: unknown; })		Additional properties to publish as part of each OpenTelemetry signal, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., `%MyEnvVar%`), and can contain a fallback value (e.g., `%MyEnvVar?DefaultValue%`).
additionalResourceAttributes	{ [x: string]: unknown; } \| (() => { [x: string]: unknown; })		Additional properties to publish as part of the OpenTelemetry resource definition for all OpenTelemetry signals, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., `%MyEnvVar%`), and can contain a fallback value (e.g., `%MyEnvVar?DefaultValue%`).
addResourceAttributesToAttributes	boolean	false	Whether to add resource attributes to signal attributes.
applicationName	string		Application name to use in telemetry information. By default, it's populated by io.Connect.
definitiveInstance	boolean		Internal library property.
enabled	boolean		Whether library is enabled. If disabled, API is still usable, but methods are no-ops.
errorlessMode	boolean	false	If `true`, the library will swallow all errors, instead of propagating them.
failOnInitError	boolean		If failure to initialize library will throw upstream error.
finalExportGracePeriodMs	number		Interval in milliseconds to wait for any remaining telemetry data to be published by any apps before proceeding with the platform shutdown.
finalExportTimeoutMs	number		Interval in milliseconds to wait for any remaining telemetry data to be exported during shutdown of the platform. This is the maximum awaiting interval and the platform may shutdown before it expires if all telemetry data has already been published.
headers	{ [x: string]: string; } \| (() => { [x: string]: string; })		Additional headers to send in HTTP requests, e.g. when using HTTP exporters.
logs	LogsSettings
logSettingsOnStartup	boolean	true	If the library should log the settings used to initialize it.
metrics	MetricsSettings
platformInstance	boolean		Internal library property.
platformVersion	string		If provided, this value will be added to the metrics and span attributes and to the span filtering context (see 'filters' in TracesSettings).
registerControlMethods	boolean		Internal library property.
requestSettings	boolean	true	For Node applications: whether to attempt to request io.Insights settings from the platform when initializing;
serviceId	string		If provided, this value will be added to the metrics and traces service.instance.id attribute, unless an OTEL service object (e.g. TraceProvider) has been provided to the library with a different setting.
serviceName	string		If provided, this value will be added to the metrics and traces service.name attribute, unless an OTEL service object (e.g. TraceProvider) has been provided to the library with a different setting.
serviceVersion	string		If provided, this value will be added to the metrics and traces service.version attribute, unless an OTEL service object (e.g. TraceProvider) has been provided to the library with a different setting. attribute.
suppressDoubleInitializationWarnings	boolean	false	Suppress double initialization warnings from the OTEL SDK.
traces	TracesSettings
userId	string		If provided, this value will be added to the metrics and traces user.id attribute, unless an OTEL service object (e.g. TraceProvider) has been provided to the library with a different setting.
useSSOAuth	boolean	false	If `true`, use io.Connect's SSO login information when making requests to the OTEL collector.
useSSOAuthRawToken	boolean	true	Used if io.Connect's SSO login information contains a `token` property. If `true`, the `token` property will be used as-is. If `false`, the `token` property may be prepended with the string "Bearer ", if it does not contain an Authorization type prefix.

Properties

Property	Type	Default	Required	Description
allowedOrigins	string[]
port	MessagePort
windowId	string